'\" t
'
' Name:		tpremove.1m
'
' Completed:	12th August, 2003.
'
' Updated:	9th August, 2004.
'
' Purpose:	Describes the tpremove command.
'
' Author:	Simon Edwards, Proprius Consulting Ltd.
'
' Version:	@(#)1.1 Original (SE)
' 		@(#)1.1 Bundle handling explained (SE)
'
.TH tpremove 1M "9 August 2004" "Linuxha.net"

.SH NAME
tpremove - Remove an installed package / bundle

.SH SYNOPSIS
.TS
l l.
tpremove \fB-p\fP \fIpkg\fP [\fB-f\fP] [\fB-x\fP] [\fB-r\fP] [\fB-v\fP] ...	Remove an installed package/bundle

tpremove \fB-P\fP \fB-p\fP \fIpkg\fP [\fB-f\fP] [\fB-x\fP] [\fB-r\fP] [\fB-v\fP] ...	Preview package/bundle removal
.TE

.SH DESCRIPTION

The \fitpremove(1M)\fP utility is used to remove a specified package or bundle
from the local host. The packages in question are held in "Tar Package" 
(a.k.a. "Tarp") format. A package must currently be in 
the "installed" or "committed" states in a specified installed package 
database.

For information on the the "Tarp" format please see the \fItpintro(1M)\fP 
manual page.

.SH REMOVING SOFTWARE

The utility will remove the specified package or bundle from the installed 
package database. If the specified package is not currently installed 
an error will be given.

If you wish to remove a specified package from a bundle then the following
format to describe the package should be used:

.TS
l.
<bundle>.<package>
.TE

The package component in this instance can contain shell meta-characters,
allowing more than a single package to be removed.
The installed package database defaults to "/var/adm/tarp" - but can be 
overridden by setting the \fBTARP_DB\fP environment variable. This allows 
normal users to maintain there own environment with package management, as 
well as having a system wide package database maintained by the system
administrator.

The actions taken when a package is removed depends on a number of
conditions:

.TP 4
[1]
Whether the package is "installed" or "committed" states - packages in other
states can not be removed using this utility, see the tpfix(1M) manual page
for more details.
.TP
[2]
Whether the package has any "dependants" - that is removing this package
might cause other installed packages to fail.

.SH ARGUMENTS
The following arguments are supported by the utility - all are optional
unless otherwise stated.

.TP 4
.B -p
Mandatory argument that should be followed by the name of the package
you wish to remove.

As stated this be the name of a bundle if you wish to remove the bundle,
or simply "bundle.package" to remove a specific package from within the
bundle.
.TP
.B -f
Force the removal of the package. If this flag is not specified and the
package has a "preremove" script which gives a non-zero return code then the
removal of the package will be aborted. 

When this flag is specified the "preremove" script is still run, but the 
value of the return code will not impact whether the package is removed or not. 
.TP
.B -x
Ignore dependencies - no packages that depend on the package to remove will 
be considered for removal. Use this with care since it might cause other
packages to stop working.
.TP
.B -r
If this package has any dependants then recursively remove these packages
as well. The key point here is that the removal is recursive - any package
chosen for removal may in turn cause other packages to be removed as well.

If a package does have dependants, and either the \fB-x\fP and \fB-r\fP flags
are not specified then an error will be given.
.TP
.B -v
Verbose mode - show copious progress messages to the standard output
devices. Without this you will only see warnings (to standard output) and
errors (to standard error).

Since package removal might include removal of dependants please make use of 
this flag to ensure you know what is occuring. 

.SH REMOVING A PACKAGE
This section describes in more detail the steps taken as part of the process
of removing a package. This is useful to understand how dependants are
dealt with, and potential error conditions that might result.

The steps taken when deleting a package are as follows:
.TP 6
[1]
Check to see whether the removal is for a bundle or a package. If a bundle
has been chosen with no package name component, then the package to remove
is change to the value "bundle.*" for further processing.
.TP
[2]
Check package status. If the package is not in either of the "committed"
or "installed" states then an error will be given and the removal of the
package aborted.
.TP
[3]
A check is made against the package database to see if a "preremove" script
exists. If it does and can be made executable, then it is run. The return code
from the script is checked. If it is 0 then the removal process will 
continue. If it is another value the process will be aborted unless the 
\fB-f\fP flag has been specified on the command line.
specific versions are ignored from consideration.
.TP
[4]
Dependency checking. The list of packages that use the package to remove
is built up. If there are no dependants on this package the removal process
continues. 

However if there are dependants then the action taken depends on whether the
\fB-x\fP or \fB-r\fP flags, if any, have been specified. The argument checking 
will ensure that only one of these flags is chosen, since they are
mutually exclusive.

If the \fB-x\fP flag has been specified the list of packages that will
be impacted by the removal of the chosen package will be shown in a warning -
but if the user does not interupt the process in five seconds the removal
process will continue.

If the \fB-r\fP flag is specified then information messages are shown 
indicating the list of packages that will be removed due to being dependants
of the original package.

Finally if neither the \fB-x\fP or \fB-r\fP flags have been specified then 
an error will be given and the removal process will be aborted.

Please remember that the current version of the toolset checks dependents
based on whether the package you are deleted is part of a bundle or not. If it
is part of a bundle then the dependents are checked only within the bundle 
itself, rather than other packages.
.TP
[5]
A check is then made to ensure that the checksums and the list of files that
are installed as part of this package are actually installed. If not the 
removal process is aborted with all packages left installed.
.TP
[6]
The status of the package is changed from its current status to "removing".
.TP
[7]
All the files that were installed in this package are now archived to a
temporary directory to allow for recovery in the event of failure or an
interupt.
.TP
[8]
The status of the package is changed from "removing" to "removed".
.TP
[9]
The files that were installed as part of this package are now removed. A
warning will be generated if any of the files can not be removed.
.TP
[10]
If any files that were originally overwritten during the package installation
are available they are not restored. This is only possible if the package
was not automatically committed when it was installed.
.TP
[11]
The details of the package are now removed from the required package
database.
.TP
[12]
A check is made to ensure that any bundle defined in the package database
includes at least one installed package. If not reference to that bundle
is removed from the database.
.RE

.SS Handling Dependencies
Given the simplistic aims of the "Tarp" package format the handling of 
dependencies is similarly straightforward. The process of producing a list 
of dependent products is a front-recursive process - this will ensure that
the list of packages is such that the first one has no dependants, and thus
can be removed.

Once the list has been generated each package will be removed by recursively
calling the \fItpremove(1M)\fP command. If any of the dependants fail to be
removed then an error will be given and the complete process aborted.

If an abort does occur whilst removing dependent packages any packages already
removed will not be re-installed.

The limitations with this recursive approach are as follows:
.TP 4
[1]
No provision is made for self referential dependencies. Currently on
encountering such a dependency list the removal process will run for
ever, (or at least until it runs out of resource).
.TP
[2]
The way in which the software orders the removal of packages only works
on a list basis, rather than on a tree structure which would give better
handling of multiple products to remove with the same dependencies.
.TP
[3] 
The removal of packages is not "atomic". If a package has five dependants and
three and successfully removed, but the fourth failed the three packages
already removed will not be re-instated.
.RE

.SH REMOVAL SCRIPTS
The Tarp format includes a limited ability for the package writer to 
run a script prior to removal and after removal - these are referred to as
the "preremove" and "postremove" scripts respectively.

.SS The Pre-remove script
Obviously the "preremove" script is run prior to removing the package. The 
purpose of this script to ensure that any applications using the package are 
shutdown prior to removal of the package.

If the "preremove" script returns a non-zero exit code, then the removal of the
package will be aborted - as long as the force flag (\fB-f\fP) has not been
specified. It is important that this script does not attempt to remove the
package itself - since the software will not be able to recover the 
installation if there is an error in such cases.

.SS Post-remove script
This script is run after the package has been removed - it is typically
used to ensure any configuration done by the "postinstall" script when the
package was installed is removed - for example the removal of configuration
directories or symbolic links etc.

The exit code of this script can not affect the removal of the package, since
at this point the package has already been removed. A non-zero exit status
will simply produce a warning.

.SH EXAMPLES
The first example previews the removal of a package "dummy2" from the 
package "fred". 

.TS
l.
tpremove -P -p fred.dummy2 -v   
.TE

Since this is run in verbose mode the output shown describes if this
package could be removed, and any impacted packages if that were the case.

.TS
l.
MSG  : Previewing removal of package fred.dummy2
MSG  : fred.dummy2 indicates that packages from bundle selected.
MSG  : Package fred.dummy2 in state committed will be removed.
MSG  : Package fred.dummy2 has the following dependants:
MSG  : 
MSG  : fred.pre1
MSG  : 
MSG  : These packages will be removed if the -r flag is specified.
MSG  : 
.TE

The next example attempts to remove the package "tools" from a user's
own package database in $HOME/tarp.

.TS
l.
TARP_DB=$HOME/tarp; export TARP_DB
tpremove -p tools -v
.TE

The next example removes the package "tools2", ignoring any dependencies. Use
of the \fB-f\fP flag is made to ensure the preremove script return code is
ignored.

.TS
l.
tpremove -p tools2 -f -x
.TE

The final example shows the package "fred.dummy2" being removed, including the
removal of any packages that depend on it. Since the verbose option has been
specified the output generated is also shown.

.TS
l.
tpremove -p fred.dummy2 -v -r
.TE

The "-r" option has been specified to ensure that any dependents of this
package are also removed. The output generated for this command would look
similar to the following:

.TS
l.
MSG  : fred.dummy2 indicates that packages from bundle selected.
MSG  : Package fred.dummy2 in state committed will be removed.
MSG  : Removing package fred.dummy2
MSG  :  Removing fred.dummy2 also requires the following packages to be removed:
MSG  :  fred.pre1
MSG  :  Removing dependent package fred.pre1...
MSG  :  Package fred.pre1 removed successfully (see /tmp/tpremove.16218-fred.pre1 for details)
MSG  :  All dependent packages removed.
MSG  :  Backing up files to remove ...
MSG  :  Removing package files...
MSG  :  2 files removed successfully.
MSG  :  Removing package definition from database.
MSG  :  Successfully removed package fred.dummy2
MSG  : Removing empty bundle: fred
.TE

Two points from the last example should be highlighted:

.TP 4
[1]
Since "fred.pre1" is classed as a dependent of the package to remove it to
has been removed. Information covering the removal of that package can be
found in the another log file - as indicated in the output.
.TP
[2]
Since "fred.pre1" and "fred.dummy2" were the only packages installed for
the "fred" bundle the empty bundle was also removed once both packages
had been successfully removed.

.SH EXIT CODES
The utility makes extensive use of exit codes, you are encourgaged to check
the return code if an error occurs and refer to the following values.

.TP 4
.B 0
The specified package has been removed. If this package has dependants and the
\fB-r\fP flag has been used, then all dependants have also been removed
successfully.
.TP
.B 1
Invalid command line arguments have been specified - a usage message will
have been shown on standard errror.
.TP
.B 2
The package specified to remove is not currently installed.
.TP
.B 3
The package status is such that it can not currently be removed - this
typically occurs if the package installation or removal was aborted without
cleanup - please see the \fItpfix(1M)\fP manual page for more details.
.TP
.B 4
The utility was unable to change the status of the package during the
package removal process. This typically is due to the fact that the "status" 
file for this package in the installed package database is not writable, 
or not space exists in the relevant file system to update the file.
.TP
.B 5
The specified installed package database does not appear to exist.
.TP
.B 6
The specified package to remove has dependants, but neither the \fB-r\fP or
\fB-x\fP flags were given on the command line.
.TP
.B 7
An error was returned whilst attempting to remove a dependant package. The
error message will contain the name of the log file that contains the
error details.
.TP
.B 8
When attempting to remove the package the utility was unable to find the
file containing the information on which files were originally installed - and
hence the package can not be removed.
.TP
.B 9
The utility was unable to create a temporary directory during the package
removal process. This temporary directory is used to backup the files that
are to be removed - and exists in the installed package file system.

Please ensure you are able to write to the directory /var/adm/tarpdb, or
wherever the \fBTARP_DB\fP environment variable refers to. If you are able to
write to this directory, check the available space in the file system.
.TP
.B 10
A non-zeo return code was generated by the "preremove" script and the force
flag (\fB-f\fP) was not specified.
.TP
.B 11
Unable to save all files in the temporary directory. These files are copies of
the files to remove. See error code 9 for potential reasons for this return
code.
.TP
.B 12
The package database did not exist, and the software was unable to create it.

.SH FILES
Once the package has been removed all files relevant to the package will
have been removed, and hence this section is redundant.

.SH SEE ALSO
.BR tpintro(1M),
.BR tpinstall(1M),
.BR tppkg(1M),
.BR tplist(1M),
.BR tpchk(1M).

.SH WARRANTY/LICENSE/ENVIRONMENT
This utility is available under the GNU GPL, and comes with 
\fIno warranty or guarantee of any kind\fP.

This program is only suitable for environments that have the following
software components installed:

.TP 4
.B Shell Utilities
The following utilities are required, \fIawk(1)\fP, \fIksh(1)\fP
as well as the standard utiltiies to check, move and remove files and 
directories.
.TP
.B Perl
Any version of Perl from 4 onwards with standard installation libraries
should be suitable. Currently Perl is only used sparingly, but still must
be available.

